/******************************************************************************
 * @file rd0ff_bsp_exti_driver.h
 * @brief EXTI驱动头文件
 *
 * 详细描述：
 * - 功能1：提供EXTI驱动的函数声明、数据结构和枚举定义
 * - 功能2：实现EXTI初始化、去初始化、启动和停止等基础操作
 * - 功能3：提供中断线配置和状态管理功能
 * - 功能4：支持操作系统抽象层的临界区保护和延时功能
 *
 * @author 陈泳行 | R&D Dept. | Jin Dou Aerospace 金斗航天
 * @date 2025-7-15
 * @version 1.0.0
 *
 * @version_history
 * - 1.0.0 (2025-7-15): 初始版本，实现基本功能
 *
 * @note 本模块支持操作系统抽象，通过OS_DEFINE宏控制
 * @warning 驱动初始化前必须确保GPIO接口已正确初始化
 ******************************************************************************/
#ifndef __RD0FF_BSP_EXTI_DRIVER_H__
#define __RD0FF_BSP_EXTI_DRIVER_H__

/******************************** Includes ***********************************/
#include <stdio.h>          /* 标准输入输出库 */
#include <stdint.h>         /* 标准整数类型定义 */
#include "rd0ff_bsp_exti_config.h"  /* EXTI配置头文件 */
/******************************** Includes ***********************************/

/******************************** Defines  ***********************************/
/**
 * @brief 操作系统支持宏定义
 *
 * 配置说明：
 * - 定义OS_DEFINE启用操作系统抽象接口（如os_delay_t）
 * - 未定义OS_DEFINE则使用裸机实现，由用户提供延时函数
 *
 * @note 此宏应在项目头文件中统一配置
 */
#define OS_DEFINE 1
#define EXTI_MAX_LINES 16        /* 支持的最大EXTI线数量 */
#define EXTI_QUEUE_SIZE 32       /* 事件队列默认大小 */
/******************************** Defines  ***********************************/

/******************************** Declare ************************************/
/**
 * @brief EXTI驱动操作状态码枚举
 *
 * 此枚举定义了EXTI驱动操作中可能返回的状态码，用于错误处理和调试。
 */
typedef enum
{
    EXTI_RET_OK = 0,                  /* 操作成功                              */
    EXTI_RET_ERROR,                   /* 通用错误：未指定的错误				  */
    EXTI_RET_BUSY,                    /* 设备忙碌：设备正在处理其他操作         */
    EXTI_RET_TIMEOUT,                 /* 超时错误：操作未在规定时间内完成       */
    EXTI_RET_INVALID_PARAM,           /* 参数错误：传入的参数值无效             */
    EXTI_RET_DATA_INVALID,            /* 数据无效：接收到的数据格式错误         */
    EXTI_RET_INIT_ERROR,              /* 初始化错误：设备初始化失败             */
    EXTI_RET_DEINIT_ERROR,            /* 去初始化错误：设备去初始化失败         */
    EXTI_RET_LINE_OCCUPIED,           /* 中断线被占用：EXTI线已被其他功能使用   */
    EXTI_RET_LINE_NOT_INIT,           /* 中断线未初始化：EXTI线尚未配置         */
    EXTI_RET_CALLBACK_NULL,           /* 回调函数为空：未设置中断回调函数       */
    EXTI_RET_GPIO_ERROR,              /* GPIO错误：GPIO配置或操作失败           */
    EXTI_RET_NVIC_ERROR,              /* NVIC错误：中断控制器配置失败           */
    EXTI_RET_PRIORITY_ERROR,          /* 优先级错误：中断优先级设置无效         */
} exti_ret_t;

/**
 * @brief EXTI初始化状态枚举
 *
 * 表示EXTI驱动和各中断线的初始化状态。
 */
typedef enum
{
    EXTI_INIT = 0,                    /* EXTI已初始化                           */
    EXTI_NOT_INIT,                    /* EXTI未初始化                           */
    EXTI_LINE_ENABLED,                /* EXTI线已使能                           */
    EXTI_LINE_DISABLED,               /* EXTI线已禁用                           */
} exti_init_t;

/**
 * @brief EXTI驱动整体状态枚举
 *
 * 表示EXTI驱动的整体初始化状态。
 */
typedef enum
{
    EXTI_DRIVER_INIT = 0,             /* EXTI驱动已初始化                      */
    EXTI_DRIVER_NOT_INIT,             /* EXTI驱动未初始化                      */
} exti_status_t;/**
 * @brief EXTI设备操作结构体
 *
 * 封装EXTI设备的初始化、去初始化、使能、禁用等操作函数，
 * 以及设备句柄和初始化状态。
 */
typedef struct 
{
    void (*pfinit  )(void* gpio_port, uint32_t gpio_pin, 
                     uint32_t exti_line, bsp_exti_trigger_t trigger);  /* EXTI初始化函数指针        */
    void (*pfdeinit)(uint32_t exti_line                            );  /* EXTI去初始化函数指针      */
    void (*pfenable)(uint32_t exti_line                            );  /* EXTI使能函数指针          */
    void (*pfdisable)(uint32_t exti_line                           );  /* EXTI禁用函数指针          */
    void (*pfclear_pending)(uint32_t exti_line                     );  /* EXTI清除挂起标志函数指针   */
    uint32_t (*pfget_pending)(uint32_t exti_line                   );  /* EXTI获取挂起状态函数指针   */
    void (*pfset_priority)(uint32_t exti_line, uint32_t priority   );  /* EXTI设置优先级函数指针     */
    void (*pfcallback)(uint32_t exti_line                          );  /* EXTI中断回调函数指针       */
    exti_init_t                       exti_init;  /* EXTI初始化状态            */
    void                        *          hgpio;  /* GPIO句柄                  */
} bsp_exti_t;

/**
 * @brief OS临界区保护结构体
 *
 * 此结构体定义了进入临界区的函数指针，用于实现跨平台的
 */
typedef struct 
{
    void (*pfenter_critical)(void); /* EXTI进入临界区函数指针 */
    void (*pfexit_critical )(void); /* EXTI退出临界区函数指针 */
} os_critical_t;

/**
 * @brief 时间基准函数指针类型定义
 *
 * 用于获取系统时间基准，支持毫秒级和微秒级时间戳
 *
 * @return uint32_t 当前时间基准值
 */
typedef struct
{
	uint32_t (*pftime_base)(void );
} time_base_t;

#if OS_DEFINE
/**
 * @brief OS延迟函数指针类型定义
 *
 * 主要用于操作系统环境下实现延时功能，释放CPU资源
 *
 * @param uint32_t 延迟时间（单位：毫秒）
 */
typedef struct
{
	void (*pfos_delay)(uint32_t  );
} os_delay_t;
#endif // OS_DEFINE

/**
 * @brief EXTI驱动实例结构体
 *
 * 此结构体包含EXTI驱动的所有接口和状态信息，是驱动操作的核心数据结构。
 */
typedef struct 
{
    exti_status_t                     status;/* EXTI驱动状态       */
	bsp_exti_t 		      *			     exti;/* EXTI设备结构体指针   */
    time_base_t           *  pftimebase_port;/* 时间基准函数指针       */
#if OS_DEFINE
    os_delay_t            *    os_delay_port;/* OS延迟函数指针     */
    os_critical_t         * os_critical_port;/* OS临界区保护指针   */
#endif // OS_DEFINE
} bsp_exti_driver_t;

/**
 * @brief EXTI驱动实例初始化函数
 *
 * 初始化EXTI驱动实例，绑定硬件接口和系统服务，完成ADC和DAC的硬件初始化。
 *
 * @param exti_instance EXTI驱动实例指针
 * @param exti EXTI设备结构体指针
 * @param time_base 时间基准结构体指针
 * @param os_delay OS延迟函数结构体指针（当OS_DEFINE定义时有效）
 * @param os_critical OS临界区保护结构体指针（当OS_DEFINE定义时有效）
 *
 * @return exti_ret_t 操作结果状态码
 * @retval EXTI_RET_OK 初始化成功
 * @retval EXTI_RET_INVALID_PARAM 参数无效
 * @retval EXTI_RET_ERROR 初始化失败
 */
exti_ret_t exti_driver_inst(
                            bsp_exti_driver_t * exti_instance,
                            bsp_exti_t 		  *			  exti,
                            time_base_t       *     time_base
#if OS_DEFINE
                            ,os_delay_t        *      os_delay,
                            os_critical_t     *   os_critical
#endif // OS_DEFINE
                                                              );

/**
 * @brief EXTI线初始化函数
 *
 * 初始化指定的EXTI线，配置GPIO和中断参数
 *
 * @param exti EXTI设备结构体指针
 * @param gpio_port GPIO端口
 * @param gpio_pin GPIO引脚
 * @param exti_line EXTI线号
 * @param trigger 触发模式
 * @param priority 中断优先级
 *
 * @return exti_ret_t 操作结果状态码
 */
exti_ret_t exti_line_init(bsp_exti_t* exti, 
                         bsp_gpio_port_t gpio_port,
                         uint32_t gpio_pin,
                         bsp_exti_line_t exti_line,
                         bsp_exti_trigger_t trigger,
                         bsp_exti_priority_t priority);

/**
 * @brief EXTI线使能函数
 *
 * 使能指定的EXTI线中断
 *
 * @param exti EXTI设备结构体指针
 * @param exti_line EXTI线号
 *
 * @return exti_ret_t 操作结果状态码
 */
exti_ret_t exti_line_enable(bsp_exti_t* exti, bsp_exti_line_t exti_line);

/**
 * @brief EXTI线禁用函数
 *
 * 禁用指定的EXTI线中断
 *
 * @param exti EXTI设备结构体指针
 * @param exti_line EXTI线号
 *
 * @return exti_ret_t 操作结果状态码
 */
exti_ret_t exti_line_disable(bsp_exti_t* exti, bsp_exti_line_t exti_line);

#endif // END __RD0FF_BSP_EXTI_DRIVER_H__